<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">

<html>

<head>

<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">

<title>svn-buildpackage - maintaining Debian packages with Subversion - Introduction</title>

</head>

<body>

<p><a name="ch-intro"></a></p>
<hr>

<p>
[ <a href="index.html">previous</a> ]
[ <a href="index.html#contents">Contents</a> ]
[ 1 ]
[ <a href="ch-start.html">2</a> ]
[ <a href="ch-import.html">3</a> ]
[ <a href="ch-tasks.html">4</a> ]
[ <a href="ch-reference.html">5</a> ]
[ <a href="ch-misc.html">6</a> ]
[ <a href="ch-start.html">next</a> ]
</p>

<hr>

<h1>
svn-buildpackage - maintaining Debian packages with Subversion
<br>Chapter 1 - Introduction
</h1>

<hr>

<h2><a name="s-pur"></a>1.1 Purpose</h2>

<p>
This short document is only intended to give a short help in converting
packages to Subversion management.  It is primarily intended for developers not
really familiar with Subversion or CVS management and/or converting from
maintaining their packages using common tools (dpkg-dev, devscripts) only to
version control system Subversion.
</p>

<hr>

<h2><a name="s-why"></a>1.2 Why a version control system?</h2>

<p>
But the first question may be: why use a version control system at all?  Look
at how the source is handled by the Debian package.  First, we have the pure
upstream source, which is often maintained by another person.  The upstream
author has his own development line and releases the source in snapshots (often
called releases or program versions).
</p>

<p>
The Debian maintainer adds an own set of modifications, leading to an own
version of the upstream package.  The difference set between this two version
finally ends in Debian's .diff.gz files, and this patchset is often appliable
to future upstream versions in order to get the &quot;Debian versions&quot;.
</p>

<p>
So the obvious way to deal with source upgrades/changes is using local copies,
patch, different patchutils and scripts to automate all this, eg.  uupdate.
However, it often becomes nasty and uncomfortable, and there is no way to undo
changes that you may do by mistakes.
</p>

<p>
At this point, the Subversion system can be used to simplify that work.  It
does the same things that you normaly would do by-hand but keeps it in an own
archive (a repository).  It stores the development lines of Upstream and Debian
source, keeping them in different directories (different branches).  The
branches are wired internally (the VCS &quot;knows&quot; the history of the
file and tracks the differences between the Upstream and Debian versions).
When a new upstream version is installed, the differences between the old and
new upstream versions and the Debian version are merged together.
</p>

<p>
You can create snapshots of your Debian version (&quot;tag&quot; it) and switch
back to a previous state, or see the changes done in the files.  You can store
when commiting the file to the repository or place custom tags on the files
(&quot;properties&quot;) serving various purposes.
</p>

<hr>

<h2><a name="s-feat"></a>1.3 Features</h2>

<p>
svn-buildpackage and other scripts around it has been created to do follow
things:
</p>
<ul>
<li>
<p>
keep Debian package under revision control, which means storing different
versions of files in a Subversion repository
</p>
</li>
</ul>
<ul>
<li>
<p>
allow easy walking back trough time using svn command
</p>
</li>
</ul>
<ul>
<li>
<p>
easy retrieval of past versions
</p>
</li>
</ul>
<ul>
<li>
<p>
keep track of upstream source versions and modified Debian versions
</p>
</li>
</ul>
<ul>
<li>
<p>
easy installation of new upstream versions, merging the Debian changes into it
when needed (similar to the uupdate program)
</p>
</li>
</ul>
<ul>
<li>
<p>
automated package building in clean environment, notifying about uncommited
changes
</p>
</li>
</ul>
<ul>
<li>
<p>
create version tags when requested to do the final build and update changelog
when needed
</p>
</li>
</ul>
<ul>
<li>
<p>
allow co-work of multiple Debian developers on the same project
</p>
</li>
</ul>
<ul>
<li>
<p>
auto-configure the repository layout, making it easy to use by people without
knowing much about Subversion usage (mostly you need only the add, rm and mv
commands of svn)
</p>
</li>
</ul>
<ul>
<li>
<p>
allow to store only the Debian specific changes in the repository and merge
them into the upstream source in the build area (which nicely completes build
systems like dpatch or dbs)
</p>
</li>
</ul>
<ul>
<li>
<p>
If wished, keep the upstream tarballs inside of the repository
</p>
</li>
</ul>

<hr>

<h2><a name="s-over"></a>1.4 Contents overview</h2>

<p>
There are currently three scripts provided by the svn-buildpackage package:
</p>
<ul>
<li>
<p>
svn-inject: script used to insert an existing Debian package into a Subversion
repository, creating the repository layout as needed.
</p>
</li>
</ul>
<ul>
<li>
<p>
svn-buildpackage: exports the contents of the directory associated with the
starting directory from the Subversion repository to the clean environment and
build the package there
</p>
</li>
</ul>
<ul>
<li>
<p>
svn-upgrade: similar to uupdate, upgrades the trunk to a new upstream version,
preserving and merging Debian specific changes
</p>
</li>
</ul>

<hr>

<h2><a name="s1.5"></a>1.5 Popular repository layouts</h2>

<p>
There are different ways to store the packages in the repositories (or in
multiple repositories at your choice).  <samp>svn-buildpackage</samp> normaly
expects a directory structure similar to the one well described in the
Subversion Book, which looks like:
</p>

<pre>
     packageA/
        trunk/
        branches/
        branches/upstream
        tags/
     
     projectB/
        trunk/
        branches/
        branches/developerFoo
        tags/
</pre>

<p>
packageA above may be a typical upstream-based source package and a projectB
may be a Debian native package with a separate branch created by developerFoo
for his own experiments.  See <code><a
href="http://svnbook.red-bean.com/html-chunk/ch04s02.html">Subversion
Book/Branches</a></code> for more details about using Subversion branches.
</p>

<p>
Also note that Tags work quite different than those in CVS.  Subversion does
not maintain magic tags associated with some files.  Instead, it tracks the
file state and moves, so Tagging something means creating a copy (inside of the
Repository, harddisk-space efficient) of a certain version of the file set.  So
the Debian branch of the released package source is contained in
<samp>trunk/</samp> and is tagged by copying (mirroring) the trunk tree to
<samp>tags/DEBIAN-REVISION</samp>.  The same happens for the upstream releases.
In addition, the most recent upstream version is mirrored to
<samp>branches/upstream/current</samp>.  After few package upgrade cycles, the
directory tree may look so:
</p>

<pre>
     # svn ls -R file:///home/user/svn-repo/dev/translucency 
     branches/
     branches/upstream/
     branches/upstream/0.5.9/
     branches/upstream/0.5.9/AUTHORS
     branches/upstream/0.5.9/COPYING
     ...
     branches/upstream/0.6.0/
     branches/upstream/0.6.0/AUTHORS
     branches/upstream/0.6.0/COPYING
     ...
     branches/upstream/current/
     branches/upstream/current/AUTHORS
     branches/upstream/current/COPYING
     ... same stuff as in 0.6.0 ...
     tags/
     tags/0.5.9-1/
     ...
     tags/0.5.9-1/debian/
     tags/0.5.9-1/debian/README.Debian
     ...
     tags/0.6.0-1/
     tags/0.6.0-1/AUTHORS
     ...
     tags/0.6.0-1/debian/
     tags/0.6.0-1/debian/README.Debian
     tags/0.6.0-1/debian/changelog
     ...
     trunk/
     trunk/AUTHORS
     trunk/COPYING
     ... trunk where 0.6.0-2 is beeing prepared ...
</pre>

<p>
svn-buildpackage also supports the second repository layout suggested in the
Subversion Book (function/package) but svn-inject prefers the one documented
above.  Both svn-buildpackage and svn-upgrade should be able to auto-detect the
repository layout and the location of package files.
</p>

<p>
In theory, you do not have to follow that examples and place the trunk,
branches and tags directory on the locations you like more.  But
svn-buildpackage and other scripts won't locate the files automaticaly so you
will need to edit the .svn/deb-layout file in your working directory and set
paths.  See the old <code><a
href="file:///usr/share/doc/svn-buildpackage/CONFIG">abstract</a></code> about
how auto-detection works and the <code><a
href="file:///usr/share/doc/svn-buildpackage/examples/config.example">config
example</a></code>.
</p>

<p>
Finaly, the working directory structure on your development system may look so:
</p>

<pre>
     dev/ # base directory, may be under version control or not
     dev/foo # trunk directories of various packages
     dev/bar # contents correspond to trunk, see above
     dev/tarballs # where &quot;orig&quot; tarballs are stored, may be under VC or not
     dev/build-area # where the packages are exported temporarily and built
</pre>

<hr>

<p>
[ <a href="index.html">previous</a> ]
[ <a href="index.html#contents">Contents</a> ]
[ 1 ]
[ <a href="ch-start.html">2</a> ]
[ <a href="ch-import.html">3</a> ]
[ <a href="ch-tasks.html">4</a> ]
[ <a href="ch-reference.html">5</a> ]
[ <a href="ch-misc.html">6</a> ]
[ <a href="ch-start.html">next</a> ]
</p>

<hr>

<p>
svn-buildpackage - maintaining Debian packages with Subversion
</p>

<address>
$LastChangedDate: 2005-09-23 16:17:33 +0200 (Fr, 23 Sep 2005) $<br>
<br>
Eduard Bloch<br>
<br>
</address>
<hr>

</body>

</html>

